ATSUNextCursorPosition

OSStatus ATSUNextCursorPosition (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iOldOffset,
                     ATSUCursorMovementType iMovementType,
                     UniCharArrayOffset *oNewOffset);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iOldOffset

A value of type UniCharArrayOffset. Pass the edge offset corresponding to the initial cursor position. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If the edge offset is outside the text buffer, ATSUNextCursorPosition returns the result code kATSUInvalidTextRangeErr.

iMovementType

A value of type ATSUCursorMovementType. Pass the unit distance that the cursor was moved. See Cursor Movement Constants for a description of possible values. You must pass a value between 2 bytes and a word in length.

oNewOffset

A pointer to a value of type UniCharArrayOffset. On return, the edge offset corresponding to the new cursor position. This offset may be outside the text buffer.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in styled data from an invalid cache. In this case, either the format of the cached data does not match that used by ATSUI or the cached data is corrupt. The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUNextCursorPosition function determines the edge offset in backing store memory corresponding to the previous cursor position based on the type of cursor movement specified in the iMovementType parameter. You should call ATSUNextCursorPosition and the function ATSUPreviousCursorPosition if the initial edge offset is not at a line boundary. If the initial edge offset is at a line direction boundary, you should instead call the functions ATSURightwardCursorPosition and ATSULeftwardCursorPosition to calculate the next and previous cursor positions. Note that at a line boundary, the caret is split into a high and low caret.

Note that you may not be able to move the cursor 2-bytes, since doing so might place the cursor in the middle of a surrogate pair.

SPECIAL CONSIDERATIONS

ATSUNextCursorPosition may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.